User Guide

Form Builder allows developers to construct user entry forms which integrate with IAP (Itential Automation Platform) Workflows and Service Catalog applications. In addition to constructing forms with standard inputs, developers can create forms from imported NSO YANG Service Models using the NSO NETCONF API. This native integration with NSO Services reduces the effort of having to duplicate the development of modeling services in both IAP and NSO. With Form Builder, service models requiring changes are modified just once; changes made in NSO are
automatically available for IAP to consume.

User Interface

The following figures show the user interface in Form Builder for List View and Edit View.

List View

Label	UI Element	List View Function
1	New Form	Creates a new form.
2	Delete	Deletes form when check-box has been selected.
3	Form List	List of forms; includes the form name, who created it, when it was created, who last updated it, and when it was last updated.
4	Preview	Opens form in preview mode.
5	Edit	Opens form for editing.

Edit View

Label	UI Element	Edit View Function
1	Form Name	User must provide unique form name.
2	Data Elements	Displays list of registered NSO services.
3	Meta Data Fields	Allows user to define custom fields in the form.
4	Update	Updates form and leaves Form Editor open.
5	Settings	Opens a modal to change the settings of the Form.
6	Preview	Opens a modal to preview the Form.
7	Clone	Makes a copy of the current Form.
8	Delete Form	Deletes the current Form.
9	Close	Closes form and returns user to Forms List.
10	Add Container	Adds a Field container to the Form.
11	Delete	Drag form elements to Trashcan icon to delete.

Creating a New Form

To create a new form:

1. Open Form Builder from the Home page or the Applications menu.
2. Click New Form ( top-right corner of title bar).
3. Give the form a unique name.
4. Click Save.

NSO Service Model Form Fields

Guidelines

• To view device elements from a service model in Form Builder, you will need to specify where to find the YANG files. In newer versions of NSO adapter (4.x and higher), this is configured in the yangdirs property of the adapter.
• To view service models in older versions of NSO adapter (pre-4.x), include your yang schemas in the load-path of "ncs.conf."
• For more information on configuring the NSO adapter to get YANG, check the NSO netconf documentation for the adapter.

Create a Form Using NSO YANG Service Model

The following steps correspond to the labels shown in the figure below. To build a form on an NSO YANG service model:

1. Select the appropriate service from the Data Elements dropdown list.
   • The leafs defined in the model will automatically display below the dropdown box.
2. Drag-and-drop the fields to assign them to the form.
   • By default, the field label is the same as the leaf from the service model. See vrf_name in the example figure below.
   • To update the field label, click the field and type a new label. See owning_entity_id in the example figure, which has been updated to device.
3. Assign the Lists defined in NSO to the form.
4. Group the fields together within a Container.
   • Click the Add Container button to assign a Container to a Form.
   • Toggle the direction icon (double arrow in left corner) to arrange the Containers horizontally or vertically. Containers can also be nested within other Containers.
5. Assign a name to the Form.
6. Click Save.

Meta Data Fields

In addition to creating a form using the leafs defined in an NSO Yang service model, you can assign Meta Data Fields to a form. Three field types and a checkbox are available.

• Text Box - Allows any characters.
• Number Field - Accepts only numerical values.
• Checkbox - A Boolean field that can be checked or unchecked.
• Dropdown - Accepts one selected option from a dropdown list.

Preview a Form

Once a form is saved, click the Form Preview button (eye icon) in the title bar to preview the form.

All form fields are editable in Preview mode, even those configured as a leafref or enumeration in the yang service model, just as they are when the form is allocated to a Workflow.The figure below illustrates the dropdown list generated by an NSO leafref.

Edit Form Field Properties

Once a field has been allocated to a form, you can configure some of its properties.

1. Hover your mouse over the field.
2. Click the Configure Properties icon (top-right corner). The Configure dialog box opens.

Property	Description
Custom Label	Adds a custom label above the field.
Field Key	An internal value that identifies the field from the underlying workflow engine code. Update this value only for a Meta Data Field. Do not modify this value when the field is part of an NSO yang service model.
Field Type	When a Field Type is selected, the form will require that type of input. An error message will display if the input does not match the required type.
Info/ Tool Tip	Adds a custom tool tip that displays when your cursor is placed over the field.
Required	When checked, a Form cannot be submitted unless a value has been entered in the Number field that displays.
Read-Only	When checked, the field is visible to users but they will not be able to modify the value.
Hide Field	When checked, the field is hidden from users. The field will still be available to the underlying Workflow Engine code.
Min Length	The minimum number of characters a Text field must contain before it can be submitted. Requires the user to define a numeric value.
Max Length	The maximum number of characters a Text field may contain before it can be submitted. Requires the user to define a numeric value.
Regex Patterns	Does not apply to any fields that have been assigned an NSO leafref or enumeration.
Custom Error Message	Adds a custom error message that displays when user input is invalid. Requires that Field Type be defined.

Delete a Form Field

To remove a Form Field, click and drag the field to the Trashcan icon (bottom left). This is illustrated in the example form.  

Add a Form Builder Task to a Workflow

This section discusses how to add a Form Builder task to a workflow. It does not describe the functionality of the Workflow Builder application.

Note: If you are not familiar with the Workflow Builder application, consult the relevant user guide for clarification on any of the information discussed in this section.

You can use Form Builder to add a Form to a workflow. This allows the user to enter information as part of the business process.

To add a form to a workflow:

1. Create a new workflow, or open an existing one.

2. Select FormBuilder in the Source Application dropdown list.

3. Select ShowFormByName and add it to the workflow.

   formWorkflow Task

   

4. Configure the manual task.

   • Enter an appropriate summary and description
   • Assign it to the relevant User Group.

5. Configure the variables for the ShowFormByName task.

   • form_name: This variable is the name of the Form.

     • Select static as the Reference task.
     • Enter the name of the Form as the Reference variable.

   • instance_data: If the form values are entered by the user and not pre-populated by a previous task or external system, configure the following:

     • Select static as the Reference task.

     • Enter {} as the Reference variable.

       Edit Task

       

6. Click Update.

7. Save the workflow

8. Click the Start workflow button.

9. Navigate to the Work queue to view the task in the Available Tasks list.

10. Click the task to initiate the work.

Example VRF Form from Workflow

Outgoing Data Format Example

{
  "/ncs:services/ip_vrf:ip_vrf": [
    {
      "owning_entity_id": "mgracl_iosxr0",
      "vrf_name": "Test-vrf",
      "address_family_type": "ipv4",
      "rd": "65001:1",
      "asn": "65001",
      "rt": [
        {
          "fp_direction": "import",
          "route_target": "65001:56"
        },
        {
          "fp_direction": "export",
          "route_target": "65001:56"
        }
      ]
    }
  ]
}

Note: The internal reference to the Form Field retains the original value before it was renamed. For example, the device field in the above figure maintains the label of 'owning_entity_id' as specified in the Yang service model.